<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>Compilation with libQGLViewer</title>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <link href="qglviewer.css" rel="stylesheet" type="text/css" />
  <link rel="shortcut icon" href="images/qglviewer.ico" type="image/x-icon" />
  <link rel="icon" href="images/qglviewer.icon.png" type="image/png" />
<script type="text/javascript">

  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-23223012-2']);
  _gaq.push(['_trackPageview']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();

</script>
</head>

<body>

<div class="banner">
  <a class="qindex" href="index.html">Home</a>
  <a class="qindex" href="download.html">Download</a>
  <a class="qindex" href="examples/index.html">Gallery</a>
  <a class="qindex" href="refManual/hierarchy.html">Documentation</a>
  <a class="qindex" href="developer.html">Developer</a>
</div>

<h1>Compilation with libQGLViewer</h1>

These instructions assume that you have <a href="download.html">installed</a> Qt and libQGLViewer.<br/>
They detail how to compile a program that uses the libQGLViewer library.
They assume you created a folder for your project (probably a copy of one of the <a hreh="examples/index.html">examples</a>), with your sources and a <code>myApp.pro</code> project file. 

<p>
<a href="#windows"><img src="images/windows.png" width="55" height="54" align="middle" alt="windows"/></a> &nbsp; &nbsp; &nbsp; &nbsp;
<a href="#mac"><img src="images/mac.png" width="55" height="54" align="middle" alt="mac"/></a> &nbsp; &nbsp; &nbsp; &nbsp;
<a href="#linux"><img src="images/linux.png" width="49" height="54" align="middle" alt="linux"/></a>
</p>


<a name="windows"></a>
<h2><img src="images/windows.png" width="55" height="54" alt="windows"/>Compilation on Windows</h2>

<h3>Using Qt Creator</h3>
Open <code>myApp.pro</code> in Qt Creator then compile and run. 


<h3>Using <code>make</code></h3>
Launch the <i>Qt command prompt</i> from the Qt folder in the <i>Start</i> menu. Then type:

<pre>
cd path\to\myApp
qmake
mingw32-make
myApp
</pre>


<h3>Using Visual Studio</h3>

Launch Visual Studio from the Qt folder in the <i>Start</i> menu and then use the Qt menu to open the <code>.pro</code> file. All parameters should be properly configured and your program should compile.

Make sure you link with the Release version of Qt if you build in Release mode.

<div class="small">
With Visual Studio 6, use <i>File-Open workspace</i> to open the <code>.dsp</code> generated by <code>qmake</code> from the <code>.pro</code>.
</div>

<h3>Providing <code>QGLViewer#VERSION_MAJOR#.dll</code></h3>

The <code>QGLViewer#VERSION_MAJOR#.dll</code> (or <code>QGLViewer#VERSION_MAJOR#d.dll</code> in debug mode) has to be found in order to execute your application.

<ul>
	<li>Copy it in a shared standard library directory such as <code>C:\Windows\System32</code>,</li>
	<li>or copy it in each application's directory,</li>
	<li>or add the path to the dlls using <code>set PATH=%PATH%;C:\Users\...\libQGLViewer-#VERSION#\QGLViewer\release</code></li>
</ul>

<!--
<div class="small">

Other non standard <code>dll</code>s that need to be found:
<ul>
<li>The Qt libraries (<code>QtCore4.dll, QtGui4.dll, QtOpenGL4.dll</code> and <code>QtXml4.dll</code>), which standard location is <code>C:\Qt\<i>date</i>\bin</code>.</li>
<li>The MinGW <code>mingwm10.dll</code>, usually located in <code>C:\Program Files\MinGW\bin</code>.</li>
</ul>

<p>
If you used the libQGLViewer installation package, these <code>dll</code>s were installed in <code>C:\Program Files\libQGLViewer\examples</code>.
</p>
</div>
-->


<!-- 
<p>
Qt 2.3 users have to first edit the examples' <code>.pro</code> files (uncomment two lines and remove end of
file as explained. Remove <code>QT_DLL</code> from <code>DEFINES</code> for Visual Studio 7). If no
<code>Project created</code> dialog is displayed when you open the <code>.pro</code>, try to run
Visual with Administrator priviledges. With Qt 2.3, you also have to add <code>/GX /GR</code> in
<i>Project-Settings-C-C++, Project options</i> before compilation.
</p>
 -->

<div class="small">
See also how to <a href="#pro">customize your .pro</a> or the advices for <a href="installWindows.html">libQGLViewer installation on Windows</a>.
</div>







<a name="mac"></a>
<h2><img src="images/mac.png" width="55" height="54" alt="mac"/>Compilation on Mac</h2>

<h3>Using Qt Creator</h3>
Open <code>myApp.pro</code> in Qt Creator then compile and run. 

<h3>Using Xcode</h3>
<pre>
cd path/to/myApp
qmake -spec macx-xcode
open myApp.xcodeproj
</pre>
Then compile your project.

<h3>Using <code>make</code></h3>
<pre>
cd path/to/myApp
qmake -spec macx-g++
make
open myApp.app
</pre>


<h3>Path customization</h3>

The standard installation will install the libQGLViewer framework in <code>~/Library/Frameworks</code>, where it can be
accessed from any application.

<p>
Use <code>install_name</code> and read Apple's
"<a href="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPFrameworks/Tasks/CreatingFrameworks.html">Creating a Framework</a>" 
as well as Qt's "<a href="http://qt.nokia.com/doc/4.6/deployment-mac.html">Deploying an Application on Mac OS X</a>" if you customize your path.
</p>

Use the <code>LIBS *= -L/path/to/lib -lQGLViewer</code> Unix syntax if you compiled a dylib instead of a framework.

<div class="small">
See also how to <a href="#pro">customize your .pro</a> or the <a href="installUnix.html#mac">libQGLViewer on Mac</a> installation page.
</div>

<!--

The compilation on Mac is essentially identical to the one described above in the linux section (<code>libQGLViewer.so</code> is named <code>libQGLViewer.dylib</code> instead).
Simply replace the above lines by:
</p>

<pre>
[bash] > export DYLD_LIBRARY_PATH=${DYLD_LIBRARY_PATH}:/path/to/qglviewerdylib
[tcsh] > setenv DYLD_LIBRARY_PATH ${DYLD_LIBRARY_PATH}:/path/to/qglviewerdylib
</pre>

You can safely ignore the prebound warning. Building a prebound library creates overlapping address
ranges. This requires further investigations and any help is more than welcome.

<p>
If you get a <code>declaration of C function 'void qObsolete' conflicts with previous declaration</code> or a
<code>template with C linkage</code> error message, try to install libQGLViewer somewhere else:
</p>

<pre>
cd QGLViewer
make uninstall
qmake INCLUDE_DIR=/usr/local/include (for instance)
make install
</pre>

Tune your <code>.pro</code> accordingly and recompile your program. Any
explanation or cleaner solution is more than welcome.

-->






<a name="linux"></a>
<h2><img src="images/linux.png" width="49" height="54" alt="linux"/>Compilation on Linux</h2>

<h3>Using Qt Creator</h3>
Open <code>myApp.pro</code> in Qt Creator then compile and run. 

<h3>Using <code>make</code></h3>
<pre>
cd path/to/myApp
qmake
make
./myApp
</pre>

<!--
The optional <code>PREFIX, INCLUDE_DIR</code> and <code>LIB_DIR</code> parameters are those you used
if you customized your <code><a href="installUnix.html#linux">make install</a></code>. Use
<code>QGLVIEWER_STATIC=yes</code> to link with the static version of the library.
These commands can also be typed in the <code>examples</code>' main directory to compile <i>all</i> the examples.

If you installed the RPM, the examples' source files are in
<code>/usr/share/doc/QGLViewer/examples</code> (may have to be copied to a place where you have
write permission). If you have downloaded the tarball instead, simply go to the
<code>examples</code> directory. Then,
-->

<div class="small">

libQGLViewer uses the <code>-Wl,-rpath</code> syntax so that your executable finds the library.
In case you are prompted with an <code>error while loading shared libraries</code> message when executing the program, fix that path. 
An other option is to copy <code>libQGLViewer.so</code> (created when you compiled the QGLViewer library) to your app's directory, 
or (better) move it to a standard library directory (such as <code>/usr/lib</code>, as is done when you <code>make install</code>).
<br/>
<!-- 
If you don't have sufficient privileges to do that, you can also add the path to the <code>libQGLViewer.so</code> to
your default library path (use <code>LD_LIBRARYN32_PATH</code> instead on some Unix flavors):

<pre>
[bash] > export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/path/to/qglviewerlib
[tcsh] > setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/path/to/qglviewerlib
</pre>
-->

Some configurations may require you to add <code>LIBS *= -lXi</code> in the <code>.pro</code> file.
Debian users may have to replace <code>-lQGLViewer</code> by <code>-lQGLViewer-2</code> in their <code>.pro</code>.

<p>
See also how to <a href="#pro">customize your .pro</a> or the <a href="installUnix.html#linux">libQGLViewer on Unix</a> installation page.
</p>
</div>




<a name="pro"></a>
<h2>Customize the <code>.pro</code> for your application</h2>

<p>
Qt uses a <code>.pro</code> file to tune the compilation settings. The one that comes with the <a href="examples/index.html">examples</a> is pretty involved since it 
tries to automatically detect where the library and headers files are located. There is no need to change it: the examples should compile out of the box.
</p>

<br/>

However, you can create a simplified <code>.pro</code> for your own projects. You need to set these three important variables in order to use libQGLViewer:
<ul>
<li><code><b>INCLUDEPATH</b></code> which must indicates where to find the QGLViewer's include files. Since the <code>#include</code>s use a <code>QGLViewer/qglviewer.h</code> syntax, 
the <code>QGLViewer</code> suffix should be omitted in this path (if libQGLViewer was installed in the <code>/xxx/yyy/QGLViewer</code> directory, you will set this variable to <code>INCLUDEPATH *= /xxx/yyy</code>).<br /> <br /></li>

<li><code><b>LIBS</b></code> which tells that your program links with libQGLViewer. Use <code>LIBS *= -L<i>/path/to/lib</i> -lQGLViewer#VERSION_MAJOR#</code>, where <code></i>/path/to/lib</i></code> is the path to the libQGLViewer lib (named <code>libQGLViewer#VERSION_MAJOR#.{so|a|dylib}</code> or <code>QGLViewer#VERSION_MAJOR#.lib</code> depending on your architecture). Use <code>-framework QGLViewer</code> instead if you compiled a Framework instead of a <code>dylib</code> on Mac (default).
<br />
<br />
</li>

<li><code><b>QT</b></code> which lists the required Qt modules: <code>QT *= opengl xml</code> is a minimum.</li>
</ul>

Here is a simple although complete <code>.pro</code> (change the paths according to your configuration):

<pre>
TARGET = myViewer
CONFIG *= qt opengl release
QT *= opengl xml

HEADERS = myViewer.h
SOURCES = myViewer.cpp main.cpp

# Windows
INCLUDEPATH *= C:/Users/login/Documents/libQGLViewer-#VERSION#
LIBS *= -LC:/Users/login/Documents/libQGLViewer-#VERSION#/QGLViewer -lQGLViewer#VERSION_MAJOR#

# Linux
INCLUDEPATH *= /home/login/Documents/libQGLViewer-#VERSION#
LIBS *= -L/home/login/libQGLViewer-#VERSION#/QGLViewer -lQGLViewer

# Mac 
INCLUDEPATH *= /Users/login/Documents/libQGLViewer-#VERSION#
LIBS *= -F/Users/login/Library/Frameworks -framework QGLViewer
</pre>

<div class="small">
If you use Visual Studio, instead of editing the <code>.pro</code>, you can add the QGLViewer's headers path (without the trailing <code>QGLViewer</code>) to <i>C/C++ / General / Additional Include Directories</i> 
and add <code>QGLViewer#VERSION_MAJOR#.lib</code> to the <i>Linker / Input / Additional Dependencies</i> using the project properties. 
These settings can also be shared by all your projects by setting the <i>Tools / Options / Directories</i> Include and Library values.
<br/>
A <code>fatal error C1083: 'QDomElement' : No such file or directory</code> is fixed by adding 
<code>XML library</code> and <code>OpenGL library</code> in <i>Project - Add Qt module</i>.

</div>




<h2>Going further</h2>

Now that your program compiles and runs, you can start improving it. You will probably start by changing the <code>draw()</code> method to define your own scene. 
Overload the <code>init()</code> function to initialize your scene as well as the OpenGL state (such as textures and objects). 
<a href="introduction.html">Read the principles</a> of the library for details. If not already done, try out the 
different <a href="examples/index.html">examples</a> and feel free to cut and paste code for the functionalities you need.

<h2>Localizing your application</h2>

See the Qt Linguist Manual for an explanation of the Qt translation model. Here are the lines you typically need to add in your <code>main</code> method to translate the texts of your interface.

<pre>
  QApplication application(argc,argv);

  QString locale = QLocale::system().name();

  QTranslator translator;
  translator.load(QString("qglviewer_") + locale);
  // translator.load(your application specific translation file(s));
  app.installTranslator(&translator); 
</pre>

This assumes that <code>qglviewer_*.qm</code> is located in your application directory. If it is not the case, copy it or use the overloaded <code>load</code> method:
<pre>
  translator.load(QString("qglviewer_") + locale, "C:\\Users\\login\\Documents\\Code\\libQGLViewer\\QGLViewer"); // for instance
</pre>

QGLViewer translation files are available in the QGLViewer's header directory.


<p>
Please <a href="mailto:contact@libqglviewer.com">let me know</a> if you encounter any problem following this guide.
</p>

<p>
  <a href="http://validator.w3.org/check/referer"><img src="images/xhtml.png" alt="Valid XHTML 1.0!" height="31" width="88"/></a>
  <a href="http://jigsaw.w3.org/css-validator/check/referer"><img src="images/css.gif" alt="Valid CSS!" width="88" height="31"/></a>
  <i>Last modified on #DATE#.</i>
</p>
    
</body>
</html>
